Description

Adds a compat/ package and a docker-compose.compat.yml overlay that lets Datadog, Jaeger, and Splunk HEC agents send telemetry to observability-stack without application code changes. Includes public-facing migration guides under docs/send-data/from-vendor/ and a contributor writing tenets section in CONTRIBUTING.md.

The overlay is opt-in and follows the existing INCLUDE_COMPOSE_* activation pattern. The base collector, its config, and all existing pipelines are unchanged.

Architecture

vendor agents ──▶ otel-collector-compat ──OTLP──▶ otel-collector (base, unchanged) ──▶ Data Prepper / Prometheus ──▶ OpenSearch
                  (new — this overlay)

OTLP apps ─────────────────────────────────────▶ (direct to base, no compat hop)

otel-collector-compat is a dedicated edge collector that runs upstream opentelemetry-collector-contrib receivers. Each receiver accepts its vendor wire protocol, translates to the OTel data model via upstream translator packages, and forwards OTLP to the base collector. All enrichment and downstream routing continues to happen in the base pipeline.

Modern OpenTelemetry SDK applications bypass the compat hop and continue sending OTLP directly to the base collector on 4317/4318.

Wire protocols supported

All upstream receiver READMEs are linked from the per-vendor docs. Attribute translation behavior is defined upstream — per-vendor docs list the 3–5 canonical attributes most users encounter and defer to upstream sources for the rest.

SignalFx is not included. The upstream signalfxreceiver is deprecated with explicit guidance to migrate to OTLP.

Activation

echo 'INCLUDE_COMPOSE_COMPAT=docker-compose.compat.yml' >> .env
docker compose up -d

Adds otel-collector-compat plus a bundled Jaeger hotrod demo on port 8080 that emits OTLP directly to the base collector (for validating the OTLP path end-to-end).

Pipelines

The compat collector uses only the batch processor — no transforms, no enrichment. Those remain in the base collector.

Validation

End-to-end validation with real vendor client libraries:

Gotchas discovered during validation (documented in vendor pages):

• Datadog: 128-bit trace IDs from Datadog-instrumented services are feature-gated upstream (Enable128BitTraceID, off by default). Trace IDs appear with upper 8 bytes zeroed without the flag.
• Datadog: Manual tracer.trace() spans get SPAN_KIND_UNSPECIFIED — the upstream receiver only assigns explicit kinds for HTTP/DB/gRPC/AWS SDK span names.
• Splunk HEC: host.name gets overwritten downstream by the base collector's resource detection. Users relying on HEC host for per-sender identification should route it to a different attribute via hec_metadata_to_otel_attrs.
• Splunk HEC: HEC has no native severity field; severityText/severityNumber will be empty. Python logging levels from clients like splunk_handler are embedded in the event body, not structured.
• Splunk HEC: Client libraries vary in how they ship custom fields (HEC fields vs. JSON-serialized event). Verify your client's behavior before relying on field-level queries.

Starlight docs build was validated with npm run build — 115 pages built, all internal links resolve.

Documentation

New public docs under docs/starlight-docs/src/content/docs/send-data/from-vendor/:

• index.md — overview, architecture, decision table, port customization, links to viewing data
• datadog.md — migration guide with decision table, DD_AGENT_HOST setup per library, canonical attribute mapping, caveats
• jaeger.md — OTLP path + legacy wire protocol path, decision table, configuration examples
• splunk.md — HEC endpoint setup, decision table, canonical metadata mapping, caveats including the host.name and severity findings above

Sidebar entry added via astro.config.mjs; cross-link from /docs/send-data/ overview.

CONTRIBUTING.md extended with a new "Writing Tenets (for agents)" section covering: framing, maintenance hygiene, accuracy, public-doc page structure, repo README conventions, and the principle that real-validation caveats are more trustworthy than theoretical ones.

Files

New:

• compat/README.md — overview + decision table + activation
• compat/collector/config.compat.yaml — edge collector config
• compat/collector/README.md — developer notes (local dev workflow, debug verbosity)
• compat/vendors/{datadog,jaeger,splunk}/README.md — thin repo READMEs pointing to public migration guides
• docker-compose.compat.yml — overlay service definitions (edge collector + hotrod)
• docs/starlight-docs/.../from-vendor/{index,datadog,jaeger,splunk}.md — public migration guides

Changed:

• docker-compose.yml — one line added to include: block (INCLUDE_COMPOSE_COMPAT)
• docs/starlight-docs/astro.config.mjs — one sidebar entry
• docs/starlight-docs/src/content/docs/send-data/index.md — one cross-link
• CONTRIBUTING.md — new Writing Tenets section

Not included (future work)

• Legacy Jaeger wire protocol end-to-end validation with a real jaeger-client-* application (modern OTLP path is validated; the jaegerreceiver loads cleanly)
• DogStatsD end-to-end with a real DogStatsD client (receiver loads; no dedicated integration test)
• Instrumented example applications under compat/examples/ for Python and Go Datadog SDKs

Issues Resolved

N/A — no pre-existing issue.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.